docs: TypeGPU functions #1793

iwoplaza · 2025-10-08T10:37:02Z

No description provided.

github-actions · 2025-10-08T10:38:18Z

pkg.pr.new

packages
Ready to be installed by your favorite package manager ⬇️

https://pkg.pr.new/software-mansion/TypeGPU/typegpu@946f45f4e404e7de8b450211cf0557cb8180dda6

https://pkg.pr.new/software-mansion/TypeGPU/@typegpu/noise@946f45f4e404e7de8b450211cf0557cb8180dda6

https://pkg.pr.new/software-mansion/TypeGPU/unplugin-typegpu@946f45f4e404e7de8b450211cf0557cb8180dda6

benchmark
view benchmark

commit
view commit

reczkok

Actually 10/10 docs - I would read them for fun even though I know all those things 🙇

reczkok · 2025-10-29T16:05:55Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx


-In order to construct a TypeGPU function, you need to start by defining its shell, an object holding only the input and output types.
+:::note[WGSL enthusiasts!]
+Don't let the JavaScript scare you! TypeGPU functions can be implemented using either WGSL or JS, both being able to call one another.


Maybe discourage over scare? Scare sounds a little condescending to me.

reczkok · 2025-10-29T16:07:30Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

+const main = () => {
+  'use gpu';
+  // Call from another function
+  return neighborhood(1.1, 0.5);


Those numbers are quite carefully chosen I see 😄 I think we should either wrap them in d.f32() or at least explain the dangers of using plain literals (eg: showing the 1.0 case)

EDIT: I just now reached a section where you explain it in depth - maybe we should do a short warning with a reference to that in case people get trigger happy and do not reach that?

reczkok · 2025-10-29T16:11:23Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

+To make this all work, we perform a small transformation to functions marked with `'use gpu'`, leaving all other code untouched. Every project's setup is different, and we want to be as non-invasive as possible. The [unplugin-typegpu](/TypeGPU/tooling/unplugin-typegpu) package hooks into existing bundlers and build tools, extracts ASTs from TypeGPU functions and compacts them into our custom format called [tinyest](https://www.npmjs.com/package/tinyest). This metadata is injected into the final JS bundle, then used to efficiently generate equivalent WGSL at runtime.
+
+:::tip
+If you wish for all WGSL generation to happen at build time, combine [unplugin-macros](https://github.com/unplugin/unplugin-macros) and our [resolve API](/TypeGPU/fundamentals/resolve).


all WGSL generation at build time is not possible most of the time so we shouldn't sell it like that - maybe all build time known WGSL generation?

reczkok · 2025-10-29T16:20:43Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

+* **Operators** --
+JavaScript does not support operator overloading.
+This means that, while you can still use operators for numbers,
+you have to use supplementary functions from `typegpu/std` (*add, mul, eq, lt, ge...*) for operations involving vectors and matrices, or use a fluent interface (*abc.mul(xyz), ...*)


We could mention the //ts-ignore (no @ since of course there is a user with that username) trick for people who like cursed code 😅

I wouldn't want people to abuse that and feel like we're endorsing it, as it introduces more problems down the line (result inferred as any, not working properly on the CPU)

reczkok · 2025-10-29T16:21:43Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

+* **Math.\*** --
+Utility functions on the `Math` object can't automatically run on the GPU, but can usually be swapped with functions exported from `typegpu/std`.


We could mention that constants are fine

reczkok · 2025-10-29T16:26:54Z

apps/typegpu-docs/package.json

+    "starlight-typedoc": "^0.19.0",
    "tinybench": "^3.1.0",
-    "typedoc": "^0.28.13",
-    "typedoc-plugin-markdown": "^4.3.0",
+    "typedoc": "^0.27.9",


Is there a particular reason for this change?

There is, the newer versions of these packages didn't generate any API Reference docs, but they also didn't fail the nr build command.

aleksanderkatan

Great docs!
I leave some nits

aleksanderkatan · 2025-10-30T14:27:43Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

-TypeGPU functions let you define shader logic in a modular and type-safe way.
+**TypeGPU functions** let you define shader logic in a modular and type-safe way.
 Their signatures are fully visible to TypeScript, enabling tooling and static checks.
 Dependencies, including GPU resources or other functions, are resolved automatically, with no duplication or name clashes.


The dependencies are resolved automatically, but the externals are collected automatically only with unplugin & TGSL, do we want to mention it here?

aleksanderkatan · 2025-10-30T14:34:47Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

+//    ^?
+
+// #2) Used to generate WGSL
+const wgsl = tgpu.resolve({ externals: { main } });


I'd be a little more explicit here, since this is close to the very beginning of the docs.

Suggested change

const wgsl = tgpu.resolve({ externals: { main } });

const wgsl = tgpu.resolve({ template: "", externals: { main } });

I really think we should add a simplified resolve api btw

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

aleksanderkatan · 2025-10-30T14:47:05Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

+```
+
+TypeGPU then propagates those types into the function body and analyses the types returned by the function.
+If it cannot unify them into a single type, it will throw an error.


them may be ambiguous here

Suggested change

If it cannot unify them into a single type, it will throw an error.

If it cannot unify the types found in different return statements into a single type, it will throw an error.

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

cieplypolar

Wonderful docs! Easy to read yet comprehensive 🦖

cieplypolar · 2025-10-31T15:02:07Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

+:::
+
+* **Calling other functions** --
+Only functions marked with `'use gpu'` can be called from within a shader. An exception to that rule is [`console.log`](/TypeGPU/fundamentals/utils#consolelog), which allows for tracking runtime behavior


Only functions marked with 'use gpu' - what about shelled functions? They don't have to be marked with 'use gpu', however we can call them from within a shader.

cieplypolar · 2025-10-31T15:17:13Z

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

    return getGradientColor((in.uv[0] + in.uv[1]) / 2);
  }`.$uses({ getGradientColor });
 ```



I think we should include an example using the TypeGPU function in addition to raw WGSL. When using TypeGPU functions, we need to explicitly name the in parameter, for example: (input) => { ... }.

I am not sure I understand what you mean 👀

cieplypolar · 2025-10-31T15:29:59Z

apps/typegpu-docs/src/content/docs/fundamentals/variables.mdx


 ## Storage and uniform variables

 When using TypeGPU for resolution, there is no need to ever define either `var<uniform>` or `var<storage[, address_space]>`, as such definitions are added automatically.


Suggested change

When using TypeGPU for resolution, there is no need to ever define either `var<uniform>` or `var<storage[, access_mode]>`, as such definitions are added automatically.

cieplypolar · 2025-10-31T15:42:15Z

apps/typegpu-docs/src/content/docs/fundamentals/buffers.mdx

 | `var<uniform>`             | `root.createUniform()`  |
 | `var<storage, read>`       | `root.createReadonly()` |
 | `var<storage, read_write>` | `root.createMutable()`  |



I will add a comment about as('...'), because we can make buffer a fixed resource.

Start wotk on better docs for JS Kernels

e468491

iwoplaza added 2 commits October 9, 2025 11:52

More work on the docs

1d6e462

Merge branch 'main' into docs/js-kernels

777ef75

iwoplaza changed the title ~~docs: JS Kernels~~ docs: TypeGPU functions Oct 16, 2025

iwoplaza added 6 commits October 16, 2025 22:15

More docs

f86dbf3

Merge branch 'main' into docs/js-kernels

08433ec

More updates

eafeeab

More updates

ad890a9

MORE

d7a2af3

Merge branch 'main' into docs/js-kernels

946f45f

iwoplaza marked this pull request as ready for review October 29, 2025 15:07

iwoplaza requested review from aleksanderkatan, cieplypolar, lursz and reczkok October 29, 2025 15:07

reczkok approved these changes Oct 29, 2025

View reviewed changes

iwoplaza merged commit 12b2d38 into main Oct 29, 2025
3 checks passed

iwoplaza deleted the docs/js-kernels branch October 29, 2025 17:05

aleksanderkatan restored the docs/js-kernels branch October 30, 2025 14:21

aleksanderkatan reviewed Oct 30, 2025

View reviewed changes

cieplypolar reviewed Oct 31, 2025

View reviewed changes

		* Math.\* --
		Utility functions on the `Math` object can't automatically run on the GPU, but can usually be swapped with functions exported from `typegpu/std`.

	const wgsl = tgpu.resolve({ externals: { main } });
	const wgsl = tgpu.resolve({ template: "", externals: { main } });

	If it cannot unify them into a single type, it will throw an error.
	If it cannot unify the types found in different return statements into a single type, it will throw an error.


		## Storage and uniform variables

		When using TypeGPU for resolution, there is no need to ever define either `var<uniform>` or `var<storage[, address_space]>`, as such definitions are added automatically.

Uh oh!

docs: TypeGPU functions #1793

docs: TypeGPU functions #1793

Uh oh!

Conversation

iwoplaza commented Oct 8, 2025

Uh oh!

github-actions bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

reczkok left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aleksanderkatan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cieplypolar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Oct 8, 2025 •

edited

Loading